Phone Number Validation

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

This document explains the phone number validation and cleaning logic used across the application. It focuses on the clean_phone_number function that standardizes phone numbers by removing non-digit characters except plus signs, handling international number formatting, and validating length constraints (minimum 7, maximum 15 digits). It also documents the regex-based cleaning process, validation criteria, supported formats, and integration with the validation API endpoint and error handling strategies.

The phone number validation spans two layers:

• Python backend service that exposes validation and parsing endpoints

• Electron frontend that integrates with the backend and Pyodide for manual number parsing

Diagram sources

• app.py

• validate_number.py

• parse_manual_numbers.py

• extract_contacts.py

• pyodide.js

• WhatsAppForm.jsx

• main.js

• preload.js

• requirements.txt

Section sources

• app.py

• validate_number.py

• parse_manual_numbers.py

• extract_contacts.py

• pyodide.js

• WhatsAppForm.jsx

• main.js

• preload.js

• requirements.txt

• clean_phone_number: The core function that cleans and validates phone numbers according to the specified rules.

• Validation API endpoint: Exposes POST /validate-number to validate a single phone number.

• Manual number parser: Parses manually entered phone numbers with optional names and applies the same cleaning logic.

• Contact extraction utilities: Provide clean_phone_number for CSV, TXT, and Excel files.

Key behaviors:

• Removes separators and spaces: hyphens, spaces, parentheses, dots

• Keeps digits and plus signs

• Strips leading zeros when not international

• Adds a leading plus for long numbers that look international

• Validates digit count between 7 and 15

Section sources

• validate_number.py

• app.py

• parse_manual_numbers.py

• extract_contacts.py

The validation pipeline integrates the frontend and backend as follows:

• Frontend collects manual numbers and invokes Pyodide to run Python parsing

• Alternatively, the backend exposes a validation endpoint for external clients

• Both paths converge on the same clean_phone_number logic

Diagram sources

• WhatsAppForm.jsx

• pyodide.js

• parse_manual_numbers.py

• app.py

• validate_number.py

clean_phone_number Implementation#

The function performs a series of regex-based transformations and validations:

• Input sanitization: strip whitespace and coerce to string

• Separator removal: remove hyphens, spaces, parentheses, dots

• Character filtering: keep only digits and plus signs

• Leading zero handling: strip leading zeros unless international

• International prefix injection: add plus for long numbers that look international

• Length validation: ensure digit count is between 7 and 15

Diagram sources

• validate_number.py

• app.py

• parse_manual_numbers.py

• extract_contacts.py

Section sources

• validate_number.py

• app.py

• parse_manual_numbers.py

• extract_contacts.py

Validation API Endpoint#

The backend exposes a POST endpoint to validate a single phone number:

• Request: JSON body with “number”

• Response: JSON with “valid”, “cleaned_number”, and “original”

• Error handling: returns 400 for missing number, 500 for exceptions

Diagram sources

• app.py

Section sources

• app.py

Manual Number Parsing Integration#

The Electron frontend uses Pyodide to run Python parsing for manual numbers:

• The frontend calls parseManualNumbers which loads Pyodide and executes parse_manual_numbers.py

• The Python module applies clean_phone_number to each candidate and returns structured results

Diagram sources

• WhatsAppForm.jsx

• pyodide.js

• parse_manual_numbers.py

Section sources

• WhatsAppForm.jsx

• pyodide.js

• parse_manual_numbers.py

Contact Extraction Utilities#

The backend provides utilities to extract contacts from various file formats. Each utility uses the shared clean_phone_number function to normalize numbers before returning structured contact data.

Section sources

• app.py

• app.py

• app.py

• extract_contacts.py

• extract_contacts.py

• extract_contacts.py

• Python backend depends on Flask, CORS, pandas, openpyxl, xlrd, and werkzeug

• The frontend uses Pyodide to execute Python code in the browser for manual number parsing

• The Electron main process handles IPC communication with the renderer process

Diagram sources

• requirements.txt

• pyodide.js

• main.js

• app.py

• validate_number.py

Section sources

• requirements.txt

• pyodide.js

• main.js

• app.py

• validate_number.py

• Regex operations are linear in input length; the function performs a small fixed number of passes

• Length checks are O(1) after digit extraction

• For large datasets, prefer batch processing via file uploads rather than repeated API calls

• Consider caching cleaned numbers if the same numbers are processed multiple times

Common validation failures and causes:

• Too short or too long: numbers with fewer than 7 or more than 15 digits after cleaning

• Invalid characters: presence of non-digit characters besides plus signs after cleaning

• Ambiguous international format: numbers starting with 0 and fewer than 11 digits are treated as national and leading zeros are stripped

Integration tips:

• When using the validation endpoint, ensure the request body contains a “number” field

• When parsing manual numbers, separate name and number with colon or dash; the system attempts to detect which part is the number

• If Pyodide fails to load, verify network connectivity and that the Python script path is correct

Section sources

• app.py

• parse_manual_numbers.py

• pyodide.js

The phone number validation and cleaning logic is centralized in clean_phone_number, which is reused across the backend endpoints and frontend Pyodide integration. It provides robust normalization and validation with clear constraints, enabling reliable downstream processing for mass messaging workflows.